docs(dotfiles): plan agent skill release refresh - #1986

Commit the promised per-source evidence

This marks the first five research batches and their source ledgers complete, but the shipped reference files contain only numbered title/URL lists: they do not record the fetch method, retrieval result, source date/version, or per-source distilled finding required by this plan's execution model. Without those fields, the assertion that all 201 pages were successfully fetched and inspected cannot be reproduced, and later reviewers cannot distinguish inspected evidence from an unverified or dead link; add the required ledger data before declaring these batches complete.

Useful? React with 👍 / 👎.

Register this worktree with git-spice

Fresh evidence in this revision is that the execution model now requires git-spice branch track, but this completion record still says the actual feature worktree was initialized with native gh stack, while line 109 marks initialization complete. That leaves the current feature work outside the mandatory git-spice stack workflow even though later sessions will trust initialization as done; register it with git-spice and update the completion record before continuing.

AGENTS.md reference: AGENTS.md:L306-L309

Useful? React with 👍 / 👎.

Stop recommending the version-gated uv audit command

Fresh evidence after the earlier fix is that SKILL.md now warns that uv audit is preview-only and absent from older releases, but this directly linked reference still tells agents to use it unconditionally. In the inspected repository environment, uv 0.7.22 --help lists no audit command and uv audit --help returns unrecognized subcommand 'audit', so following this reference aborts without performing an audit; use the documented uvx pip-audit workflow or explicitly gate a preview command by uv version.

Useful? React with 👍 / 👎.

Target the project when invoking pip-audit

Fresh evidence after the earlier uv-audit fix is that, in a uv-managed project, the bare uvx pip-audit invocation recommended here audits the uvx tool environment rather than the project's dependencies: uvx --help describes uvx as “Run a command provided by a Python package,” while pip-audit's no-argument mode audits its current environment. Following this guidance can therefore produce a clean result while vulnerable packages remain in uv.lock; require an explicit supported lockfile/requirements target or run pip-audit inside the synchronized project environment.

Useful? React with 👍 / 👎.

Parse the file JSON before using it

When this source-relative config example is copied into real code, Bun.file(...).json() yields an unvalidated loose value and the snippet immediately propagates it to the generated output, so a syntactically valid but incorrectly shaped config is accepted despite the skill's boundary-validation guidance. Parse the result with the config schema before using or rewriting it.

AGENTS.md reference: packages/dotfiles/AGENTS.md:L47-L48

Useful? React with 👍 / 👎.

Validate required connection URLs before constructing clients

When DATABASE_URL is absent, this passes undefined to an optional Bun SQL constructor instead of failing during configuration parsing, allowing Bun's implicit connection configuration to select an unintended default; the Redis example below repeats the same pattern with REDIS_URL. Parse both required URLs once and pass the validated strings so missing deployment configuration fails immediately.

AGENTS.md reference: packages/dotfiles/AGENTS.md:L46-L48

Useful? React with 👍 / 👎.

Validate REDIS_URL before creating the client

Fresh evidence after the earlier connection-URL finding is that the SQL example now parses DATABASE_URL, but this Redis example still passes Bun.env.REDIS_URL directly. When the variable is missing, the optional constructor argument selects Bun's default Redis endpoint instead of failing, so copied code can write to localhost or another unintended instance; parse the required URL with the environment schema before constructing the client.

AGENTS.md reference: packages/dotfiles/AGENTS.md:L46-L48

Useful? React with 👍 / 👎.

Audit all locked targets, not only the active environment

Fresh evidence after the earlier uvx fix is the new claim that this invocation audits “environments, requirements, and lockfiles.” It runs pip-audit against only the environment synchronized for the current interpreter and platform: uv run --help describes --with only as “Run with the given packages installed,” while uv export --help separately exposes --all-packages, extras, and dependency-group selection. In a universal uv lock or workspace, dependencies for other platforms/Python versions, nondefault groups, extras, or other members can therefore remain unaudited while this command passes; use an explicit supported lock/requirements target or export and audit every supported target.

Useful? React with 👍 / 👎.

Gate modern Git subcommands by installed version

When this mandatory skill is loaded in an environment using Git 2.43, this initial inspection block aborts: the installed git config -h documents --list as an action and has no list subcommand, while git hook -h likewise exposes only run, so the later git hook list also fails. Use the portable git config --list --show-origin --show-scope form and either version-gate newer commands or provide compatible alternatives; merely asking the agent to print git --version does not prevent it from executing the unsupported examples.

AGENTS.md reference: packages/dotfiles/AGENTS.md:L5-L7

Useful? React with 👍 / 👎.

Gate merge-tree --quiet by installed Git version

When this mandatory Git skill is used with the repository environment's Git 2.43, this mergeability check aborts with unknown option 'quiet'; the inspected git merge-tree -h lists --write-tree, --messages, and related options but no --quiet. The rewrite promotes a Git 2.50-era feature from a versioned release note to an unconditional operational recipe, so version-gate it or provide the portable pre-2.50 invocation.

AGENTS.md reference: packages/dotfiles/AGENTS.md:L5-L7

Useful? React with 👍 / 👎.

Invoke the selected TypeScript compiler explicitly

When this skill is used in this monorepo, these bare tsc commands inspect the compatibility compiler rather than the selected native TypeScript 7 compiler: tsc --version in the inspected checkout reports Version 6.0.3, while scripts/compliance-check.ts:64-67,305-307 requires PATH=node_modules/@typescript/native/bin:$PATH tsc because packages install both compilers. This can make version and resolved-config checks contradict the surrounding TypeScript 7 guidance; use the repository's Turbo task or the explicit native compiler path for these commands.

AGENTS.md reference: AGENTS.md:L66-L66

Useful? React with 👍 / 👎.

Gate geometric-repack by the installed Git version

When this mandatory skill is used in the repository’s installed Git 2.43 environment, the unconditional git maintenance run --task=geometric-repack recipe aborts with error: 'geometric-repack' is not a valid task; the skill’s release notes themselves place the newer maintenance tasks in Git 2.50. Version-gate this command or provide a compatible pre-2.50 alternative, as was done for the other recently added Git commands.

AGENTS.md reference: packages/dotfiles/AGENTS.md:L5-L7

Useful? React with 👍 / 👎.